Skip to content

fix(desktop): clarify CLI runtime setup#2680

Open
atishpatel wants to merge 8 commits into
mainfrom
agent/windows-onboarding-verify
Open

fix(desktop): clarify CLI runtime setup#2680
atishpatel wants to merge 8 commits into
mainfrom
agent/windows-onboarding-verify

Conversation

@atishpatel

Copy link
Copy Markdown
Contributor

Why

Installing the Codex, Claude, or Goose desktop app does not install the command-line harness Buzz needs. The current UI makes that distinction unclear, links some missing-CLI states to adapter documentation, and can report a successful install from the installer exit code even when runtime discovery still fails. On Windows, Buzz also invokes Goose's Bash installer, which writes the executable somewhere Buzz does not discover.

What

  • distinguish missing vendor CLIs from missing or outdated ACP adapters in runtime metadata and UI guidance
  • link Codex, Claude Code, and Goose missing-CLI states to their official CLI installation documentation
  • explain in Settings, onboarding, and agent configuration that the desktop app alone is not sufficient
  • use Goose's official PowerShell installer on Windows
  • refresh PATH and rediscover the requested runtime after installation, keeping the control retryable if the runtime is still unavailable
  • add Rust and Playwright regression coverage for Windows installer selection, CLI/adapter guidance, false-success prevention, verified installs, and onboarding copy

Risk Assessment

Medium. This changes desktop onboarding and runtime installation behavior. Successful installs now require the runtime catalog to verify availability; previously hidden discovery failures will surface as actionable errors instead of a false success state.

References

Validation

  • just desktop-typecheck
  • just desktop-test — 3,455 passed
  • focused Rust post-install verification tests
  • focused Playwright Doctor/onboarding coverage (in progress; CI and local sequential rerun will provide final results)

Generated with Codex

Co-authored-by: Atish Patel <atish@squareup.com>
Signed-off-by: Atish Patel <atish@squareup.com>
Co-authored-by: Codex <noreply@openai.com>
Comment thread desktop/src-tauri/src/managed_agents/discovery.rs Outdated
atishpatel and others added 2 commits July 23, 2026 22:41
Co-authored-by: Atish Patel <atish@squareup.com>
Signed-off-by: Atish Patel <atish@squareup.com>
Co-authored-by: Codex <noreply@openai.com>
Co-authored-by: Atish Patel <atish@squareup.com>
Signed-off-by: Atish Patel <atish@squareup.com>
Co-authored-by: Codex <noreply@openai.com>
@atishpatel
atishpatel marked this pull request as ready for review July 24, 2026 14:00
@atishpatel
atishpatel requested a review from a team as a code owner July 24, 2026 14:00
Co-authored-by: Atish Patel <atish@squareup.com>
Signed-off-by: Atish Patel <atish@squareup.com>
Co-authored-by: Codex <noreply@openai.com>
@wpfleger96

Copy link
Copy Markdown
Member

hey @atishpatel — consolidated review feedback from two independent passes at 77ac443. One important item, the rest minor/nits (flagging everything for completeness, so weigh accordingly). The core of the change is solid: deriving success from the verified step results instead of installer exit codes is the right fix for the false-success state, the 05/05b specs pin both sides of the new contract, and the CLI-vs-adapter guidance split reads cleanly. We also verified all four vendor doc URLs resolve and that the Goose PowerShell installer honors CONFIGURE=false with the escaping as written (the command runs through Git Bash, so \$env:CONFIGURE reduces to a literal $ for PowerShell — correct).

1. (important, flagged independently by both reviewers) AgentDefinitionDialog.tsx:628-634 branches on selectedRuntime.id === "buzz-agent" to decide whether not_installed means "CLI is missing." That's a hardcoded harness-ID check in render code, which desktop/src/features/agents/AGENTS.md rule 1 explicitly rules out — harness capability facts have exactly one source, the Rust runtime catalog. It also duplicates runtime semantics in the UI: the next bundled/non-vendor runtime would incorrectly be described as missing a CLI unless another ID exception gets added. Worth noting the cli_missing branch and the vendor not_installed branch already produce byte-identical strings, so exposing the fact from the catalog (or a named guidance kind on AcpRuntimeCatalogEntry) removes both the rule violation and the duplication in one move.

2. (minor) post_install_verification.rs calls the full discover_acp_runtimes(), whose probe phase spawns auth probes (10s timeout each) for every available runtime — verification only needs the phase-1 availability classification for the one runtime being installed. On a machine with claude and goose already signed in, every install click pays up to ~10s of dead probe time inside the blocking task. A probe-free availability lookup would fix it.

3. (minor) The Goose Windows installer is pinned to the mutable main branch (raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1) while Unix pulls from the stable release. Looks unavoidable today — the stable release doesn't ship download_cli.ps1 (we checked, it 404s) — but it means the script's env contract can drift under Buzz without a Goose release. Deserves a comment in the catalog naming that constraint, and ideally an upstream ask to attach the .ps1 to stable so both platforms pin the same way.

4. (minor) In DoctorSettingsPanel.tsx, an available but logged-out/config-invalid runtime still gets an action labeled "CLI install guide" — at that point the user needs sign-in or config repair, not installation. "CLI setup guide," or only showing install guidance for unavailable states, would be more accurate.

5. (nit) post_install_verification.rs interpolates the availability enum with {status:?}, so users see Debug output like NotInstalled verbatim in the error text. A small display mapping would read better.

6. (nit) SetupStep.tsx:387-392 — the cli_missing and not_installed branches return the identical string; could collapse to one condition.

7. (nit) Two unrelated blank-line deletions in AgentDefinitionDialog.tsx (around the effect at ~415/424) are pure diff noise.

Item 1 is the only merge-blocker from our side. CI is fully green at head.

atishpatel and others added 2 commits July 24, 2026 10:10
Move external CLI guidance into runtime catalog metadata and make post-install rediscovery targeted and auth-probe-free. Clarify setup labels and the Goose Windows installer constraint.

Co-authored-by: Atish Patel <atish@squareup.com>
Signed-off-by: Atish Patel <atish@squareup.com>
Co-authored-by: Goose <opensource@block.xyz>
Resolve the Doctor runtime-row conflict by preserving main's per-row install state and the review follow-up's CLI setup label.

Co-authored-by: Atish Patel <atish@squareup.com>
Signed-off-by: Atish Patel <atish@squareup.com>
@atishpatel

Copy link
Copy Markdown
Contributor Author

🤖 Addressed all seven review items in f19b483 (included in current merge head 9d1faf2):

  1. Removed the AgentDefinitionDialog runtime-ID exception. The Rust catalog now exposes requires_external_cli (derived from KnownAcpRuntime metadata), the IPC/TypeScript projection carries it, and render code uses that catalog fact for CLI-missing guidance.
  2. Extracted reusable phase-1 runtime discovery and changed post-install verification to query only the installed runtime without running catalog-wide authentication probes.
  3. Documented why Goose Windows intentionally uses the official mutable main-branch PowerShell script: the stable release currently publishes only the Unix installer. No upstream issue was opened from this PR.
  4. Renamed the Doctor action to “CLI setup guide,” which remains accurate for install, sign-in, and configuration-repair states.
  5. Replaced Rust Debug enum output such as NotInstalled with human-readable availability labels in verification errors.
  6. Collapsed the identical cli_missing and not_installed onboarding detail branches into one condition.
  7. Restored the two unrelated blank lines in AgentDefinitionDialog to remove diff noise.

The branch was also merged with current origin/main; GitHub CI is the validation gate for head 9d1faf2.

atishpatel and others added 2 commits July 24, 2026 11:37
Keep main's per-runtime mutation state without retaining the optimistic-success binding removed by post-install verification.

Co-authored-by: Atish Patel <atish@squareup.com>
Signed-off-by: Atish Patel <atish@squareup.com>
Co-authored-by: Codex <noreply@openai.com>
Align Doctor E2E assertions with the review-requested CLI setup guide label.

Co-authored-by: Atish Patel <atish@squareup.com>
Signed-off-by: Atish Patel <atish@squareup.com>
Co-authored-by: Codex <noreply@openai.com>
@atishpatel
atishpatel enabled auto-merge (squash) July 24, 2026 19:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants